Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.env.example:
- Around line 39-43: The .env.example redirect URI is incorrect: update the
documentation to instruct registering the redirect URI as
<your-domain>/auth/login-callback to match the actual callback used by the code
(startSignin() in src/api/services/OIDC.ts); change the text that currently says
<your-domain>/auth/callback to <your-domain>/auth/login-callback so operators'
provider redirect URI matches the startSignin() behavior.

In `@prisma/seed/createMissingLogtoUsers.ts`:
- Around line 37-89: The Logto user creation (the POST to
`${LOGTO_ENDPOINT}/api/users` inside the for (const user of users) loop
producing response/body and logtoId) is non-idempotent and runs before the
Prisma transaction (db.$transaction) so failures leave orphaned Logto users;
change the flow to perform local preflight and use an existing Logto user if
present or move the Logto creation until after the transaction succeeds, or if
you must create it before the DB changes implement a compensating delete of that
Logto user (using logtoId) inside the catch/failure path of the db.$transaction
block; reference the variables/functions response, body, logtoId,
db.$transaction, tx.user.create, and tx.user.delete to locate where to add the
preflight check or compensating delete.
- Line 61: The progress logs in createMissingLogtoUsers.ts currently print raw
PII (user.email and identity provider IDs) to the console (see the
console.error/console.log calls that include user.email and any provider ID
values); change those log statements to avoid emitting full emails or stable
provider IDs by replacing them with a non-PII identifier (e.g., user.id, a
truncated/masked email like user.email.replace(/(.{2}).+(@.+)/, '$1***$2'), or a
short hash of the email) and remove or mask any provider ID strings before
logging, preserving the original message context (body.message or JSON) but not
the raw PII.
- Around line 58-65: Add a runtime type-narrowing guard before reading body.id:
after parsing body from response, verify body is a non-null object and that
typeof body.id === 'string' (and optionally typeof body.message === 'string' if
you access it); if the check fails, log an error including the raw body and
continue the loop instead of assigning to logtoId or performing DB operations.
Update the block around the existing response/body logic (where response.json()
is assigned and logtoId is set) to enforce this guard and handle the
invalid-response path safely.

In `@prisma/seed/migrateOidcSubs.ts`:
- Line 57: The stdout uses raw identifiers (mapping.identifier and
mapping.zitadel_id) which may expose emails and provider subject IDs; replace
those console.log calls in migrateOidcSubs.ts with masked versions (e.g., show
only first 1–3 chars + redacted placeholder or hash) or emit counts-only
messages; update both the log that currently prints mapping.identifier and
mapping.zitadel_id and the similar log later in the file to use a
mask/obfuscation helper (e.g., maskEmail/maskId) or a summarized message so no
full email or subject ID is written to stdout.
- Around line 51-87: Before calling tx.user.create with mapping.logto_id, detect
if a target user already exists and handle it instead of blindly creating—use
db.user.findUnique or tx.user.findUnique to check for a row with id ===
mapping.logto_id; if found, either move FK references to that existing target
and delete the source (perform the same FK UPDATE loop and source delete) or
skip this mapping and increment skipped, and only create the temporary/migrating
row when no target exists; update the logic in the block around tx.user.create /
tx.$executeRawUnsafe / tx.user.delete / tx.user.update to branch on the
existence of mapping.logto_id to avoid duplicate-key failures and half-completed
transactions.

In `@README.md`:
- Line 51: Fix the typo and wording in the README string that mentions the
example compose file: change "directoy" to "directory" and capitalize/format
"docker compose" as "Docker Compose" in the sentence that reads "You can find an
example docker compose file in the [example](./example/) directoy." Ensure the
updated sentence references the example directory and uses "Docker Compose"
consistently.

In `@schema.graphql`:
- Around line 2817-2819: OfflineUser now marks family_name and given_name
nullable, but fastUserQuery spreads OfflineUser into layout data and components
may assume non-null names; update the downstream consumers to defensively handle
nulls by coalescing or conditional-rendering: locate usages of
OfflineUser/family_name and OfflineUser/given_name in fastUserQuery results and
in components receiving layout data (search for fastUserQuery, layoutData
spread, and components that read family_name/given_name), then replace direct
access with safe fallbacks (e.g., use displayName = family_name ?? given_name ??
email ?? '' or conditionally render name blocks) so no runtime errors occur when
those fields are null while leaving ImpersonatedUser/ImpersonationUser handling
unchanged.

In `@src/api/context/oidc.ts`:
- Around line 123-137: Replace the inline role-parsing blocks that push into
OIDCRoleNames (the branches that read rolesRaw and the Object.keys path) with a
shared helper (e.g., parseOidcRoles or extractOidcRoleNames) that accepts
unknown rolesRaw and the allowed oidcRoles set/array and returns a string[] of
validated role names; inside the helper treat the input as unknown, narrow types
(Array.isArray, typeof element === 'string', element is object with typeof
element.name === 'string'), do NOT use any casts, extract the name string when
present, and filter the results against the allowed oidcRoles so only
'admin'|'member'|'service_user' are returned; replace both occurrences (user and
impersonated-user paths) to call this helper and append its returned values to
OIDCRoleNames.
- Around line 154-199: The code currently uses
decodeJwt(impersonationTokenSet.data.access_token) which does no signature
verification; replace this with a cryptographic verification using jwtVerify()
against the OIDC issuer JWKS (reuse the same JWKS fetching/verification logic
used for id_token verification in this file) to validate the impersonation
access_token before trusting its claims, then extract the verified payload and
use that to look up the DB user (symbols: decodeJwt -> jwtVerify,
impersonationTokenSet.data.access_token, issuer/JWKS fetch routine,
db.user.findUnique, impersonatedUser). Also ensure the actor check uses the
verified token payload (act.sub) and on verification failure or actor mismatch
delete the impersonation cookie (impersonationTokenCookieName), abort
impersonation and return the same token response path as currently implemented.

In `@src/api/resolvers/modules/auth.ts`:
- Around line 70-89: The code currently asserts custom JWT claims on
ctx.oidc.user into claims and casts values directly into hasPassword,
mfaVerificationFactors, ssoIdentities, and socialIdentities; add runtime
validation instead of blind casts by implementing small type guards (e.g.,
isBooleanClaim, isStringArrayClaim, isSsoIdentitiesArrayClaim that checks
objects have issuer and identityId strings) and use them when reading claims
from ctx.oidc.user/claims so that invalid shapes set the GraphQL fields to null
(or a safe default) rather than casting; alternatively, if you choose the
type-level fix, update the OIDCUser type to explicitly declare password, mfa,
sso_identities, and social_identities so the compiler enforces shapes at the
source (referencing ctx.oidc.user, claims, hasPassword, mfaVerificationFactors,
ssoIdentities, socialIdentities).

In `@src/api/resolvers/modules/impersonation.ts`:
- Around line 262-266: The resolver is accepting args.scope but never forwarding
it to performTokenExchange, so callers think down-scoping occurs while it is
ignored; update the impersonation resolver to pass args.scope into
performTokenExchange (e.g., performTokenExchange(ctx.oidc.tokenSet.access_token,
args.targetUserId, args.scope)) or alternatively remove the GraphQL scope
argument from the schema and resolver signature; look for usages of
performTokenExchange and args.scope in impersonation.ts and either forward
args.scope through the call or delete the scope argument and all references to
it.

In `@src/api/resolvers/modules/user.ts`:
- Around line 432-436: The current spreads use truthy checks (e.g.,
...(issuerUserData.family_name && { family_name: issuerUserData.family_name }))
which drop empty-string values; change these to nullish checks so intentional
empty values are preserved—replace each truthy guard for
issuerUserData.family_name, issuerUserData.given_name, and
issuerUserData.preferred_username with a nullish check (e.g., use
issuerUserData.family_name != null ? { family_name: issuerUserData.family_name }
: {} ) so only null/undefined are omitted while empty strings are allowed
through.

In `@src/api/services/OIDC.ts`:
- Around line 353-364: The token exchange builds tokenExchangeParams but omits
the actor_token fields so impersonation tokens are never bound; modify the
exchange to include actor_token and actor_token_type (use the existing
actorToken variable and set actor_token_type to
'urn:ietf:params:oauth:token-type:access_token') when actorToken is present, so
the request sent from the function that creates subjectToken and performs the
token exchange includes those fields and the resulting JWT contains the act
claim expected by the verification in src/api/context/oidc.ts.
- Around line 174-180: The decodeAccessTokenClaims helper currently returns
unverified claims from decodeJwt; stop merging those into session by either
verifying the access_token signature against the issuer JWKS before returning
claims (reuse the same JWKS verification logic used for id_token) or replace
usage with a server-side call to the userinfo endpoint to obtain authoritative
claims—update callers that merge claims into session to use the
verified/userinfo result instead of decodeAccessTokenClaims. Also fix
performTokenExchange to include the provided actorToken by adding an actor_token
entry to the tokenExchangeParams body so the token exchange request binds the
actor (preserve the existing subject_token behavior and include actor_token
alongside it).

In `@src/config/public.ts`:
- Line 11: Change the optional URL/string zod schemas to first normalize empty
strings to undefined using z.preprocess so empty env values are treated as
unset; specifically update the schemas for PUBLIC_OIDC_ACCOUNT_URL,
PUBLIC_SENTRY_DSN, PUBLIC_BADGE_GENERATOR_URL, PUBLIC_DOCS_URL (and in the other
config file for OIDC_M2M_RESOURCE and SENTRY_DSN) to use z.preprocess(v => v ===
"" ? undefined : v, z.string().url().optional() or z.string().optional() as
appropriate) so the existing nullish-coalescing logic (??) works and empty
strings no longer fail validation.

In `@src/routes/`(authenticated)/my-account/+page.svelte:
- Around line 193-263: The action anchors that render only an icon need
accessible names: update each <a class="btn btn-ghost btn-sm"
href={accountUrl(...)}> (used with accountUrl('username'), accountUrl('email'),
accountUrl('password'), accountUrl(hasPasskey ? 'passkey/manage' :
'passkey/add'), accountUrl(hasTotp ? 'authenticator-app/replace' :
'authenticator-app'), and accountUrl(hasBackupCodes ? 'backup-codes/manage' :
'backup-codes/generate')) to include either an appropriate aria-label (e.g.,
"Change username", "Change email", "Change password", "Manage passkeys" / "Add
passkey", "Replace authenticator app" / "Set up authenticator app", "Manage
backup codes" / "Generate backup codes") or add visually hidden text inside the
anchor so screen readers and keyboard users get descriptive labels; ensure
labels reflect the conditional text determined by hasPasskey, hasTotp, and
hasBackupCodes.

---

Nitpick comments:
In `@src/routes/`(authenticated)/my-account/+page.server.ts:
- Around line 62-65: The fallback accountCenterUrl building currently uses
string concatenation which can create malformed URLs; update the logic that sets
accountCenterUrl to use the URL API instead of concatenation: if
configPublic.PUBLIC_OIDC_ACCOUNT_URL is present use it, otherwise construct a
new URL('/account', configPublic.PUBLIC_OIDC_AUTHORITY.replace(/\/oidc\/?$/,
'')) (or equivalent using new URL with eventUrl.origin as needed) so paths are
joined correctly; keep the existing accountRedirectUrl
(`${eventUrl.origin}/my-account`) behavior unchanged or likewise build it via
new URL('/my-account', eventUrl.origin) for consistency.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.env.example:
- Line 249: The file .env.example is missing a trailing newline; edit the file
so that the final line "# PUBLIC_SHA=abc123" is terminated with a newline
character (i.e., add an empty line at EOF) to satisfy dotenv-linter and standard
POSIX text file conventions.

---

Nitpick comments:
In `@src/api/services/OIDC.ts`:
- Around line 57-67: The current heuristic splits normalized.name on the last
space which can misassign multi-part names; change the logic in OIDC.ts (the
block that manipulates normalized.given_name and normalized.family_name) to only
split when parts.length === 2 (set given_name = parts[0], family_name =
parts[1]); for single-word names keep the existing fallback (set given_name =
normalized.name and family_name = normalized.name or leave family_name undefined
as your policy dictates), and for names with more than two parts avoid applying
the "last-space" split (e.g., set given_name = normalized.name and leave
family_name undefined) so you don't incorrectly map multi-part names.

In `@src/routes/`(authenticated)/my-account/+page.svelte:
- Around line 32-44: The effect currently calls toast.success whenever
data.accountUpdateSuccess is truthy which can re-fire on unrelated re-renders;
add a small local tracker (e.g., a module-scoped variable like lastShownSuccess
or a Set) outside the $effect to remember the last shown value, then inside the
$effect compare data.accountUpdateSuccess to that tracker and only call
toast.success(successMap[... ]()) and update the tracker when the value is new;
ensure you still handle different string keys (email, password, username,
passkey, mfa, backup-codes) and optionally clear the tracker when
accountUpdateSuccess is cleared so future updates can show again.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/api/services/OIDC.ts`:
- Around line 324-348: createSubjectToken currently derives the Management API
base URL directly from the issuer; change it to mirror getM2MAccessToken by
using configPrivate.OIDC_M2M_RESOURCE with a fallback of
`${issuer.replace(/\/oidc\/?$/, '')}/api`. Update createSubjectToken to compute
managementApiBase = configPrivate.OIDC_M2M_RESOURCE ??
`${issuer.replace(/\/oidc\/?$/, '')}/api` and then POST to the subject-tokens
endpoint relative to that base (e.g., `${managementApiBase}/subject-tokens`)
while keeping the existing headers, body, timeout, and error handling; reference
createSubjectToken, getM2MAccessToken, and configPrivate.OIDC_M2M_RESOURCE when
making the change.

---

Duplicate comments:
In @.env.example:
- Line 253: Add a trailing newline (LF) at the end of the .env.example file so
the final line containing the commented variable "# PUBLIC_SHA=abc123" ends with
a newline character; simply ensure the file terminates with a newline to satisfy
dotenv-linter and POSIX text-file conventions.

In `@src/api/services/OIDC.ts`:
- Around line 379-400: The token exchange omits the actor token fields so the
impersonation JWT lacks the `act` claim; update the code that builds
tokenExchangeParams (in the same function that calls createSubjectToken and
reads actorToken) to add actor_token = actorToken and actor_token_type =
'urn:ietf:params:oauth:token-type:access_token' when actorToken is present
(i.e., only attach these two keys if actorToken is truthy), so the token
exchange request includes the actor and downstream verification of decoded.act
will work.

---

Nitpick comments:
In `@src/api/services/OIDC.ts`:
- Around line 57-67: The current name-splitting in OIDC (logic touching
normalized.name, normalized.given_name, normalized.family_name) assumes Western
order and duplicates single-word names into both given and family names; change
it to only split when there are at least two words and avoid duplicating the
single-word case—i.e., if parts.length >= 2 set normalized.given_name =
parts.slice(0, -1).join(' ') and normalized.family_name = parts[parts.length -
1], otherwise leave normalized.given_name and normalized.family_name unset (or
set family_name to undefined) and rely on normalized.name for display; add a
brief comment noting the heuristic limitation instead of forcing potentially
incorrect family/given values.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/api/services/OIDC.ts`:
- Line 258: Replace the type assertion on remoteUserInfo by using the
isValidOIDCUser type guard to let TypeScript narrow the type: call
isValidOIDCUser(remoteUserInfo) and return remoteUserInfo directly from inside
that conditional branch (and handle the failure path consistently—throw or
return the appropriate error/undefined) instead of using "as OIDCUser";
reference the isValidOIDCUser function and the remoteUserInfo variable in
OIDC.ts to locate where to make this change.
- Around line 248-252: The call that falls back to fetch user info incorrectly
passes the raw access_token as the expectedSubject; update the call to pass the
actual subject (sub) or undefined instead of access_token so fetchUserInfo
receives a user ID, e.g. replace the third argument currently using "sub ??
access_token" with just "sub" (or "sub ?? undefined") and keep the surrounding
use of normalizeOIDCClaims and accessTokenClaims unchanged; check the
identifiers fetchUserInfo, normalizeOIDCClaims, access_token, sub, and
accessTokenClaims when making the change.

---

Duplicate comments:
In `@src/api/services/OIDC.ts`:
- Around line 380-401: The token exchange builds tokenExchangeParams but never
adds the actor token; update the logic in the token-exchange flow (the block
that constructs tokenExchangeParams in the function that calls
createSubjectToken and exchanges it) to add actor_token and actor_token_type
when an actorToken argument is provided: set tokenExchangeParams.actor_token =
actorToken and tokenExchangeParams.actor_token_type =
'urn:ietf:params:oauth:token-type:access_token' (matching the subject token type
used) so the returned JWT includes the act claim that src/api/context/oidc.ts
expects.

---

Nitpick comments:
In `@src/api/services/OIDC.ts`:
- Around line 41-43: Change the isValidOIDCUser parameter from any to unknown
and implement proper runtime narrowing: update the signature to
isValidOIDCUser(user: unknown): user is OIDCUser and inside the function first
check that user is a non-null object, then verify it has the required properties
(e.g. 'sub' and 'email') and optionally that those properties are strings before
returning true; reference the OIDCUser type and the isValidOIDCUser function to
locate and update the guard logic.
- Around line 314-315: The code currently does await response.json() and returns
data.access_token without checking shape; add runtime validation after calling
response.json() to ensure the parsed object has an access_token property of type
string (e.g., check typeof data?.access_token === 'string'), throw a descriptive
error if missing or invalid, and only then return the token to prevent
downstream failures when response.json() returns an unexpected shape; update the
function in OIDC.ts that performs response.json() to include this guard around
the data and access_token variables.
- Line 33: Replace the unsafe index signature "[key: string]: any" in OIDC.ts
with a safer type (e.g., "Record<string, unknown>" or "[key: string]: unknown")
and update any places that read properties from this indexed object to perform
explicit type narrowing/casting (use type guards, typeof checks, or specific
casts) before treating values as strings/numbers/objects; if you truly cannot
avoid `any`, add a narrow-scoped "// TYPE-SAFETY-EXCEPTION:" comment explaining
why and limit its use to the smallest possible symbol.
- Line 49: Change the parameter type of normalizeOIDCClaims from Record<string,
any> to Record<string, unknown> to improve type safety; update the function
signature normalizeOIDCClaims(claims: Record<string, unknown>): Record<string,
any> and then adjust any property accesses inside the function to perform
explicit type checks or narrow with type assertions (e.g., typeof checks or
Array.isArray) before using claim values so compilation is satisfied and runtime
behavior remains unchanged.